/**
 * 自动化相关类型定义
 *
 * @fileoverview 定义Web自动化预约系统的类型结构，包括页面类型识别、
 * 时间段管理、预约结果处理、错误信息分类等自动化流程相关的数据类型。
 *
 * 主要类型：
 * - 页面类型（PageType）- 预约流程中的页面识别
 * - 时间段信息（TimeslotInfo）- 可预约时间段数据
 * - 预约结果（BookingResult）- 预约操作执行结果
 * - 错误信息（ErrorInfo）- 自动化过程中的错误分类
 * - 日历信息（CalendarInfo）- 可用日期数据
 * - 表单字段（FormFields）- 动态表单数据映射
 * - 步骤结果（StepResult）- 单个自动化步骤的执行结果
 * - 自动化选项（AutomationOptions）- 执行参数配置
 *
 * @author System
 * @version 1.0.0
 * @since 2024
 *
 * @example
 * ```typescript
 * import type { BookingResult, TimeslotInfo, AutomationOptions } from './automation'
 *
 * const result: BookingResult = {
 *   success: true,
 *   reference_number: 'REF123456',
 *   message: '预约成功'
 * }
 * ```
 */

// ============================================================================
// 页面类型枚举
// ============================================================================

/**
 * 页面类型枚举
 *
 * @description 定义预约流程中可能遇到的各种页面类型，用于页面识别和流程控制。
 * 自动化系统根据页面类型执行相应的操作逻辑。
 *
 * @typedef PageType
 * @example
 * ```typescript
 * const currentPageType: PageType = 'calendar'
 *
 * switch (currentPageType) {
 *   case 'home':
 *     // 处理首页逻辑
 *     break
 *   case 'calendar':
 *     // 处理日历选择逻辑
 *     break
 *   default:
 *     // 处理未知页面
 * }
 * ```
 */
export type PageType
  = | 'home' /** 首页/起始页面 */
    | 'terms' /** 条款和条件页面 */
    | 'personal_info' /** 个人信息填写页面 */
    | 'identifier_check' /** 身份验证页面 */
    | 'calendar' /** 日历选择页面 */
    | 'timeslot' /** 时间段选择页面 */
    | 'confirmation' /** 确认页面 */
    | 'result' /** 结果页面 */
    | 'error' /** 错误页面 */
    | 'maintenance' /** 系统维护页面 */
    | 'unknown' /** 未识别的页面类型 */

// ============================================================================
// 时间段和日期相关类型
// ============================================================================

/**
 * 时间段信息接口
 *
 * @description 定义预约系统中可选时间段的完整信息，包括时间段ID、
 * 日期、开始结束时间等关键数据。
 *
 * @interface TimeslotInfo
 * @example
 * ```typescript
 * const timeslot: TimeslotInfo = {
 *   id: 'slot_001',
 *   date: '25-12-2024',
 *   start_time: '0900',
 *   end_time: '1000',
 *   display_time: '09:00'
 * }
 *
 * // 在自动化脚本中使用
 * await selectTimeslot(timeslot)
 * ```
 */
export interface TimeslotInfo {
  /** 时间段唯一标识符 */
  id: string
  /** 预约日期，格式：YYYY-MM-DD */
  date: string
  /** 开始时间，格式：HHMM（24小时制） */
  start_time: string
  /** 结束时间，格式：HHMM（24小时制） */
  end_time: string
  /** 显示时间，格式：HH:MM，用于UI展示 */
  display_time: string
}

/**
 * 日历信息接口
 *
 * @description 定义日历页面的可用日期信息，用于自动化系统识别和选择可预约日期。
 *
 * @interface CalendarInfo
 * @example
 * ```typescript
 * const calendarInfo: CalendarInfo = {
 *   year: '2024',
 *   month: '12',
 *   available_dates: ['25-12-2024', '26-12-2024', '27-12-2024']
 * }
 *
 * // 选择第一个可用日期
 * const selectedDate = calendarInfo.available_dates[0]
 * ```
 */
export interface CalendarInfo {
  /** 年份字符串 */
  year: string
  /** 月份字符串 */
  month: string
  /** 可用日期数组，格式：YYYY-MM-DD */
  available_dates: string[]
}

// ============================================================================
// 预约结果和错误处理类型
// ============================================================================

/**
 * 预约结果接口
 *
 * @description 定义自动化预约操作的执行结果，包含成功状态、参考号、错误码等信息。
 *
 * @interface BookingResult
 * @example
 * ```typescript
 * // 成功的预约结果
 * const successResult: BookingResult = {
 *   success: true,
 *   reference_number: 'REF20241225001',
 *   message: '预约申请提交成功'
 * }
 *
 * // 失败的预约结果
 * const failureResult: BookingResult = {
 *   success: false,
 *   error_code: '512',
 *   message: '系统繁忙，请稍后重试'
 * }
 * ```
 */
export interface BookingResult {
  /** 操作是否成功 */
  success: boolean
  /** 预约参考号（成功时提供） */
  reference_number?: string
  /** 错误代码（失败时提供） */
  error_code?: string
  /** 结果消息描述 */
  message: string
}

/**
 * 错误信息接口
 *
 * @description 定义自动化过程中遇到的错误分类和详细信息，用于错误处理和重试策略。
 *
 * @interface ErrorInfo
 * @example
 * ```typescript
 * const errorInfo: ErrorInfo = {
 *   type: 'system_busy',
 *   code: '512',
 *   message: '系统繁忙，请稍后重试'
 * }
 *
 * // 根据错误类型决定处理策略
 * switch (errorInfo.type) {
 *   case 'system_busy':
 *     // 等待后重试
 *     break
 *   case 'ip_lock':
 *     // 更换代理
 *     break
 * }
 * ```
 */
export interface ErrorInfo {
  /** 错误类型分类 */
  type: 'system_busy' | 'session_timeout' | 'ip_lock' | 'maintenance' | 'unknown_error' | 'frequent_access' | 'network_error' | 'no_record'
  /** 错误代码 */
  code: string
  /** 错误描述消息 */
  message: string
}

// ============================================================================
// 表单和数据类型
// ============================================================================

/**
 * 表单字段接口
 *
 * @description 定义动态表单字段的键值对映射，支持灵活的表单数据处理。
 *
 * @interface FormFields
 * @example
 * ```typescript
 * const formData: FormFields = {
 *   passport_number: 'E12345678',
 *   license_number: '440123199001011234',
 *   full_name: '张三',
 *   email: 'zhangsan@example.com'
 * }
 *
 * // 动态填充表单
 * for (const [field, value] of Object.entries(formData)) {
 *   await fillFormField(field, value)
 * }
 * ```
 */
export interface FormFields {
  /** 字段名到字段值的映射 */
  [key: string]: string
}

// ============================================================================
// 自动化执行相关类型
// ============================================================================

/**
 * 自动化步骤执行结果接口
 *
 * @description 定义单个自动化步骤的执行结果，包含成功状态、页面类型、数据、错误信息等。
 * 用于步骤间的数据传递和错误处理。
 *
 * @interface StepResult
 * @example
 * ```typescript
 * const stepResult: StepResult = {
 *   success: true,
 *   page_type: 'calendar',
 *   data: { available_dates: ['25-12-2024', '26-12-2024'] },
 *   html_saved: '/snapshots/calendar_20241225.html'
 * }
 *
 * // 在自动化流程中使用
 * if (stepResult.success) {
 *   processStepData(stepResult.data)
 * } else {
 *   handleStepError(stepResult.error)
 * }
 * ```
 */
export interface StepResult {
  /** 步骤执行是否成功 */
  success: boolean
  /** 当前页面类型（可选） */
  page_type?: PageType
  /** 步骤执行产生的数据（可选） */
  data?: any
  /** 错误信息（失败时提供） */
  error?: string
  /** 保存的HTML文件路径（可选） */
  html_saved?: string
}

/**
 * 自动化执行选项接口
 *
 * @description 定义自动化执行的各种配置参数，包括浏览器设置、延迟配置、超时设置等。
 * 用于控制自动化执行的行为和性能。
 *
 * @interface AutomationOptions
 * @example
 * ```typescript
 * const options: AutomationOptions = {
 *   headless: false,
 *   timeout: 30000,
 *   save_html: true,
 *   user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
 *   viewport: { width: 1920, height: 1080 },
 *   delays: {
 *     page_view: { min: 1000, max: 3000 },
 *     form_fill: { min: 100, max: 500 },
 *     pre_submit: { min: 2000, max: 5000 },
 *     step_transition: { min: 500, max: 1500 }
 *   }
 * }
 * ```
 */
export interface AutomationOptions {
  /** Job ID（可选）：用于关联UI日志记录 */
  jobId?: string
  /** 进度回调（可选）：用于上报细粒度进度与步骤 */
  onProgress?: (p: { progress: number, step: string, timestamp: number }) => void
  /** 是否使用无头模式（不显示浏览器界面） */
  headless?: boolean
  /** 操作超时时间（毫秒） */
  timeout?: number
  /** 是否保存HTML快照 */
  save_html?: boolean
  /** 用户代理字符串（会话级，可选；默认来自预约记录或系统生成） */
  user_agent?: string
  /** 浏览器视窗大小 */
  viewport?: {
    /** 视窗宽度（像素） */
    width: number
    /** 视窗高度（像素） */
    height: number
  }
  /** 人性化延迟配置 */
  delays?: {
    /** 页面浏览延迟范围（毫秒） */
    page_view?: { min: number, max: number }
    /** 表单填写延迟范围（毫秒） */
    form_fill?: { min: number, max: number }
    /** 提交前延迟范围（毫秒） */
    pre_submit?: { min: number, max: number }
    /** 步骤间过渡延迟范围（毫秒） */
    step_transition?: { min: number, max: number }
  }
}

/**
 * 预约流程上下文接口
 *
 * @description 定义自动化预约流程中的完整上下文信息，包括用户信息、偏好设置、
 * 会话数据等。在整个预约流程中传递和更新。
 *
 * @interface BookingContext
 * @example
 * ```typescript
 * const bookingContext: BookingContext = {
 *   user_info: {
 *     passport_number: 'E12345678',
 *     license_number: '440123199001011234',
 *     license_owner_name: '张三',
 *     email: 'zhangsan@example.com',
 *     phone_number: '13800138000',
 *     issuing_country: 'CN',
 *     issuing_authority: 'GD',
 *     service_type: 'DI'
 *   },
 *   preferred_dates: ['25-12-2024', '26-12-2024'],
 *   preferred_times: ['09:00-10:00', '14:00-15:00'],
 *   options: automationOptions
 * }
 * ```
 */
export interface BookingContext {
  /** 用户基本信息 */
  user_info: {
    /** 护照号码 */
    passport_number: string
    /** 驾照号码 */
    license_number: string
    /** 驾照持有人姓名 */
    license_owner_name: string
    /** 电子邮箱 */
    email: string
    /** 联系电话（可选） */
    phone_number?: string
    /** 签发国家 */
    issuing_country: 'CN' | 'OTH'
    /** 签发机关 */
    issuing_authority: 'GD' | 'OTH'
    /** 服务类型 */
    service_type: string
  }
  /** 首选预约日期列表（可选） */
  preferred_dates?: string[]
  /** 首选预约时间列表（可选） */
  preferred_times?: string[]
  /** 已选择的日期（可选） */
  selected_date?: string
  /** 已选择的时间段（可选） */
  selected_timeslot?: TimeslotInfo
  /** 表单字段数据（可选） */
  form_fields?: FormFields
  /** 会话数据（可选） */
  session_data?: {
    /** Cookie信息 */
    cookies?: any[]
    /** 时间戳 */
    timestamp?: string
  }
  /** 自动化执行选项（可选） */
  options?: AutomationOptions
}

// ============================================================================
// 自动化流程定义类型
// ============================================================================

/**
 * 自动化步骤定义接口
 *
 * @description 定义单个自动化步骤的结构，包括名称、描述、执行函数、重试策略等。
 * 用于构建可复用和可配置的自动化流程。
 *
 * @interface AutomationStep
 * @example
 * ```typescript
 * const loginStep: AutomationStep = {
 *   name: 'login',
 *   description: '用户登录步骤',
 *   execute: async (context: BookingContext) => {
 *     // 执行登录逻辑
 *     return { success: true, page_type: 'home' }
 *   },
 *   retry: {
 *     max_attempts: 3,
 *     delay_ms: 2000,
 *     backoff_factor: 2
 *   },
 *   timeout: 30000
 * }
 * ```
 */
export interface AutomationStep {
  /** 步骤名称标识 */
  name: string
  /** 步骤描述说明 */
  description: string
  /** 步骤执行函数 */
  execute: (context: BookingContext) => Promise<StepResult>
  /** 重试策略配置（可选） */
  retry?: {
    /** 最大重试次数 */
    max_attempts: number
    /** 重试延迟时间（毫秒） */
    delay_ms: number
    /** 退避倍数因子（可选） */
    backoff_factor?: number
  }
  /** 步骤超时时间（毫秒，可选） */
  timeout?: number
}

/**
 * 自动化流程定义接口
 *
 * @description 定义完整的自动化流程，包含多个有序的自动化步骤和全局配置。
 * 用于组织复杂的预约流程。
 *
 * @interface AutomationFlow
 * @example
 * ```typescript
 * const bookingFlow: AutomationFlow = {
 *   name: 'driving_license_booking',
 *   description: '驾照预约完整流程',
 *   steps: [
 *     loginStep,
 *     selectDateStep,
 *     confirmBookingStep
 *   ],
 *   options: {
 *     headless: false,
 *     timeout: 60000
 *   }
 * }
 * ```
 */
export interface AutomationFlow {
  /** 流程名称标识 */
  name: string
  /** 流程描述说明 */
  description: string
  /** 流程步骤列表 */
  steps: AutomationStep[]
  /** 流程执行选项（可选） */
  options?: AutomationOptions
}

// ============================================================================
// 解析器和工具类型
// ============================================================================

/**
 * HTML解析结果接口
 *
 * @description 定义HTML解析操作的通用结果格式，支持泛型数据类型。
 *
 * @template T - 解析数据的类型，默认为any
 * @interface ParseResult
 * @example
 * ```typescript
 * const dateParseResult: ParseResult<string[]> = {
 *   success: true,
 *   data: ['25-12-2024', '26-12-2024'],
 *   page_type: 'calendar'
 * }
 *
 * const errorResult: ParseResult<TimeslotInfo[]> = {
 *   success: false,
 *   error: '无法解析时间段信息'
 * }
 * ```
 */
export interface ParseResult<T = any> {
  /** 解析是否成功 */
  success: boolean
  /** 解析得到的数据（成功时提供） */
  data?: T
  /** 错误信息（失败时提供） */
  error?: string
  /** 解析出的页面类型（可选） */
  page_type?: PageType
}

// ============================================================================
// 管理器和引擎接口
// ============================================================================

/**
 * 页面解析器接口
 *
 * @description 定义HTML页面解析器的标准接口，提供各种页面内容解析功能。
 * 用于从HTML中提取结构化数据。
 *
 * @interface IPageParser
 * @example
 * ```typescript
 * class MyPageParser implements IPageParser {
 *   identifyPageType(html: string, url: string): PageType {
 *     // 实现页面类型识别
 *     return 'calendar'
 *   }
 *
 *   extractFormFields(html: string): ParseResult<FormFields> {
 *     // 实现表单字段提取
 *     return { success: true, data: { name: 'input[name="name"]' } }
 *   }
 * }
 * ```
 */
export interface IPageParser {
  /** 识别页面类型 */
  identifyPageType: (html: string, url: string) => PageType
  /** 提取表单字段 */
  extractFormFields: (html: string, formName?: string) => ParseResult<FormFields>
  /** 解析可用日期 */
  parseAvailableDates: (html: string) => ParseResult<string[]>
  /** 解析可用时间段 */
  parseAvailableTimeslots: (html: string) => ParseResult<TimeslotInfo[]>
  /** 解析预约结果 */
  parseBookingResult: (html: string) => ParseResult<BookingResult>
  /** 解析日历信息 */
  parseCalendarInfo: (html: string) => ParseResult<CalendarInfo>
  /** 检测错误信息 */
  detectError: (html: string) => ParseResult<ErrorInfo>
}

/**
 * 浏览器管理器接口
 *
 * @description 定义浏览器生命周期管理的标准接口，包括启动、关闭、页面管理等功能。
 *
 * @interface IBrowserManager
 * @example
 * ```typescript
 * class MyBrowserManager implements IBrowserManager {
 *   async launch(options?: AutomationOptions): Promise<void> {
 *     // 启动浏览器
 *   }
 *
 *   async newPage(): Promise<any> {
 *     // 创建新页面
 *     return page
 *   }
 * }
 * ```
 */
export interface IBrowserManager {
  /** 启动浏览器 */
  launch: (options?: AutomationOptions) => Promise<void>
  /** 关闭浏览器 */
  close: () => Promise<void>
  /** 创建新页面 */
  newPage: () => Promise<any> // Playwright Page
  /** 获取当前页面 */
  getCurrentPage: () => any | null
  /** 保存HTML内容 */
  saveHtml: (filename: string, html?: string) => Promise<string>
  /** 保存截图 */
  screenshot: (filename?: string) => Promise<string>
}

/**
 * 自动化引擎接口
 *
 * @description 定义自动化引擎的核心功能接口，包括流程执行、进度监控、取消操作等。
 *
 * @interface IAutomationEngine
 * @example
 * ```typescript
 * class MyAutomationEngine implements IAutomationEngine {
 *   async execute(context: BookingContext): Promise<BookingResult> {
 *     // 执行完整预约流程
 *     return { success: true, message: '预约成功' }
 *   }
 *
 *   getProgress(): number {
 *     // 返回当前进度 0-100
 *     return 75
 *   }
 * }
 * ```
 */
export interface IAutomationEngine {
  /** 执行完整自动化流程 */
  execute: (context: BookingContext) => Promise<BookingResult>
  /** 执行单个自动化步骤 */
  executeStep: (step: AutomationStep, context: BookingContext) => Promise<StepResult>
  /** 获取执行进度（0-100） */
  getProgress: () => number
  /** 获取当前执行步骤 */
  getCurrentStep: () => string
  /** 取消执行 */
  cancel: () => Promise<void>
}
